In general, the Redmine Importer will take the columns of a .csv file and map them to the fields of issues, and create one issue for each line of the the .csv file. It’s a good way to create Redmine issues when you have a large volume of issues to manage.

Below is a description of how to use the Importer. Also, see the SampleFiles page for a list of sample CSV files you can upload.

Select the “Import” item on the project bar and you will see the first CSV file upload screen. At this screen, you should click the “Choose File” button to select the CSV file to be uploaded. (For existing projects, in the project Settings, inside Modules, you will have to enable “Importer” for the Import item to appear.)

In the example below, the user has already selected “CustomField.csv” and is about to click the “Upload File” button.

Once you click “Upload File”, the Column Matching screen will be displayed. At this second screen, the most important thing is to confirm the mapping from your column headers to the available fields of a Redmine issue. If you are importing relationships between issues, you will also want to see the section on “Unique-valued Column” below to verify your other settings. When the options are correct, hit the “Submit” button.

Your issues will be imported and a summary of the number of records inserted and any problems found will be displayed. Note that importing a large number of issues can take a long time. If you left the “Send notification emails” checked, emails will be sent according to normal Redmine settings; if you turned that checkbox off, no emails will be sent (this can be handy when doing something like porting issues from one installation to another).

You should always provide a header row in your CSV file. The titles in this header row will help Redmine Importer figure out which column in your CSV files corresponds to which field of the Redmine issue.

It is suggested to always use UTF-8 encoding, comma as separator, and double-quote as delimiter for your CSV file. However, if you are working with CSV files from a legacy source, you can tweak the CSV file format details via the options in the CSV Upload screen.

The maximum supported size of CSV file depends on your database backend; it’s 4 megabytes for MySQL.

Here is the list of headers the Redmine will automatically recognize; they correspond to fields of a Redmine issue.Note that while they are all listed here for completeness, all fields are optional. You only need to provide data for the items you actually want to set.

If you use the column headers given above, they should automatically match no matter what language Redmine is displaying.In addition to the strings above, Redmine Importer will try to automatically match columns which are the same as the localized version of the field names in Redmine. If the columns don’t match automatically, just be sure to set the field match pulldowns in the Column Matching screen.

You should be able to use the importer to import custom fields in the same manner as built-in fields. You need to set the custom fields up in the Settings tab ahead of time; Redmine Importer will not create custom field definitions automatically.

If there is any chance of using your custom field as a unique-valued column (see below) the “Used as a filter” checkbox must be on.

In addition to the basic import functions described above, Redmine Importer supports updating existing issues, setting the parent task of an imported task, and importing task relationships. Doing so requires that one line in your imported CSV file somehow be able to refer to a pre-existing issue or another line in the CSV file.

In these situations, you must specify one column in your CSV file which is a Unique-valued Column, meaning that all the relevant tickets use a different value in this column. This enables you to use the value of that column as a unique identifier when referring to a different issue.

For instance, if you know that all the issues you are working with definitely have different Subject fields, you can use Subject as your Unique-value Column. That means that in your CSV file, when you want to refer to another row, you can refer to it by its subject.Therefore, you could import parent-child task relationships by having a CSV file like this:

However, it may be difficult to guarantee that issues will always have unique subjects, especially if your users are editing them. Therefore, another way to set up a unique column is to add a custom field in Redmine, and then use the value of the custom field as your Unique Column. If you are using Redmine Importer to transfer information from another system this may be particularly effective; the other system may already have some unique piece of information. Alternatively, if you’re exporting your CSV file from a spreadsheet, it’s quite easy to generate a time+serial number value which is unique for every line.

For instance, if you created a custom field called “External Id” and then wanted to use that as your unique column to import parent/child and dependency relationships, you might end up uploading a CSV file like this:

When creating new issues, it is only required that your unique column be unique among all the issues you are importing. If you want to update existing issues (see below), the unique column must be unique across all issues in the project.

All of the examples so far have talked about using Redmine Importer to create new issues. However, if your Unique Column values are unique across all issues in your project, you can also use Redmine Importer to update existing issues. To enable this, turn on the “Update Existing Issues” checkbox in the Column Matching screen.

In this case, Redmine Importer will use the value in the unique column to query the database and find the existing issue to update. Remember that all of the matching columns from the CSV file will be updated, so you might overwrite values that have changed in Redmine. If you want to skip a column on import, just set it to “Ignore” on the Column Matching screen.

Redmine Importer processes your CSV file in order from the beginning to the end. Because of this, when making references to other columns using unique columns, you can only refer to issues that are earlier in the CSV file. You cannot refer to issues that come further down in the file.

If this is unworkable, there’s a straightforward but non-obvious workaround: import the CSV file twice. The first time, set all of the relationship columns to “Ignore” so you’re just importing the basic data. The second time, be sure to set your Unique Column and to turn on the “Update Existing Issues” checkbox. Since all the issues will already exist in the database, they can now be found.

Redmine Importer can only have one column mapped to given field value. Because of this, it cannot import more than one issue relationship of the same relationship type in one upload. That is, while in fact Issue C may “follow” both Issue B and Issue A, because you can’t have two columns with the header “follow” you can’t import that information all at once.

The workaround is to import twice, ignoring one of the columns the first time, and turning on “Update Existing Issues” and ignoring the other column the second time.

In general, it’s fine to re-import a CSV file that declares issue relationships. Redmine Importer will check whether the relationship already exists and only create any that are missing. However, Redmine Importer cannot delete relationships, so any issue relationships that were created previously will remain in existence even if they are not in the new CSV file.

In the same way, if you re-import a file that includes a Watchers column, any new watchers will be added to the issue, but Redmine Importer never deletes existing watchers.

If you’ve been around databases, you might think that using the Redmine issue number is the obvious solution for Unique Columns. This works fine for updating: if you create a column whose header is “Id”, it will automatically be recognized as the Redmine issue number and used to refer to other tickets. However, this is often inconvenient because the Redmine issue number doesn’t exist until the issue is created – that means it’s impossible to use it to set up in an import. It can also be impractical to get the Redmine issue numbers out of Redmine after the initial creation.

In the redmine_importer/test/samples directory, there are some sample .csv files. See SampleFiles for instructions on how to set up and import all of these files, which will give you a good sense of what Redmine Importer can do.